﻿using wwl.Domain.Entities.Common;

namespace wwl.Domain.Entities.Rbac
{
  /// <summary>
  /// 用户角色关联实体（DDD 关联实体）
  /// 作为用户聚合根和角色聚合根之间的关联桥梁，实现多对多的权限分配关系
  /// 设计对齐 Camunda 的 act_id_membership 表概念，但在此作为独立关联实体实现更丰富的业务语义
  /// </summary>
  public class UserRole : BaseEntity, ITenantAware
  {
    /// <summary>
    /// 用户唯一标识（关联用户聚合根）
    /// </summary>
    /// <remarks>
    /// 1. 聚合引用：通过 UserId 引用用户聚合根，建立用户与角色的关联关系，但不包含用户详细信息。
    /// 2. 外键约束：在数据库层面通过外键约束确保关联的用户存在，维护引用完整性。
    /// 3. 性能优化：仅存储用户标识而非完整用户信息，减少数据冗余，提升查询和存储效率。
    /// 4. 业务一致性：确保用户角色关联与用户本身的租户归属一致，避免跨租户的权限混乱。
    /// </remarks>
    public string UserId { get; set; } = string.Empty;

    /// <summary>
    /// 角色唯一标识（关联角色聚合根）
    /// </summary>
    /// <remarks>
    /// 1. 权限来源：通过 RoleId 确定用户权限的具体来源，建立"用户-角色-权限"的完整链条。
    /// 2. 级联删除：当角色被删除时，通过数据库外键级联删除所有相关用户角色关联，确保数据清洁。
    /// 3. 权限验证：在权限校验时通过 RoleId 快速定位角色及其权限集合，支撑高效的访问控制。
    /// 4. 租户对齐：确保角色与用户在同一个租户下，维护多租户权限体系的一致性。
    /// </remarks>
    public string RoleId { get; set; } = string.Empty;

    /// <summary>
    /// 租户标识（多租户关联隔离）
    /// </summary>
    /// <remarks>
    /// 1. 租户边界：确保用户角色关联关系在正确的租户上下文内，防止跨租户的权限泄漏。
    /// 2. 数据分区：通过 TenantId 实现用户角色数据的分区存储和查询，提升多租户系统性能。
    /// 3. 一致性校验：在创建用户角色关联时验证用户、角色、关联三者的租户一致性。
    /// 4. 系统级支持：TenantId 为 null 表示系统级关联，通常用于系统管理员等特殊场景。
    /// </remarks>
    public string? TenantId { get; set; }

    /// <summary>
    /// 操作类型
    /// </summary>
    /// <remarks>
    /// 1. 业务追踪：记录对用户角色关联的操作类型，支持权限变更的审计和追溯。
    /// 2. 状态管理：通过操作类型区分关联的当前状态（分配/撤销/更新），支撑业务逻辑判断。
    /// 3. 默认值：默认为 ASSIGN（分配），确保历史数据和新创建数据的兼容性。
    /// 4. 扩展支持：预留操作类型字段，便于未来扩展更多权限管理功能（如临时授权、过期回收等）。
    /// </remarks>
    public string OperationType { get; set; } = "ASSIGN";

    /// <summary>
    /// 用户导航属性（EF Core 关系配置）
    /// </summary>
    /// <remarks>
    /// 1. 延迟加载：通过 virtual 关键字实现按需加载，在需要用户详细信息时才执行查询。
    /// 2. 关系完整性：通过 Fluent API 配置与 User 聚合根的一对多关系，确保导航属性的正确性。
    /// 3. 业务便利：通过导航属性可直接访问关联用户的详细信息，支持"通过角色找用户"的业务场景。
    /// 4. 性能注意：在批量处理时应避免 N+1 查询问题，通过 Include 显式加载优化性能。
    /// </remarks>
    public virtual User User { get; set; } = null!;

    /// <summary>
    /// 角色导航属性（EF Core 关系配置）
    /// </summary>
    /// <remarks>
    /// 1. 权限追溯：通过导航属性可直接访问关联角色的权限信息，支持完整的权限分析。
    /// 2. 缓存优化：角色信息相对稳定，可通过缓存提升通过用户角色关联查询角色信息的性能。
    /// 3. 业务场景：支持"通过用户找角色"和"通过角色找权限"的完整权限追溯需求。
    /// 4. 设计对齐：与 Camunda 的成员关系概念一致，但在此通过导航属性提供更丰富的业务支持。
    /// </remarks>
    public virtual Role Role { get; set; } = null!;
  }
}